# AI Cleaner Log — 청소 파워 부스트(Boost) 로직 개선

작성일: 2026-06-04
대상 브랜치: `feat/no-right-sensor`

## 1. 작업 목표

`boostCleaningPower()`가 파워를 올리자마자 같은 호출 안에서 즉시 원상복귀하던 동작을,
**먼지 감지 시 5초간 파워를 부스트한 뒤 자동으로 기본 파워로 복귀**하도록 변경한다.

## 2. 변경 전 문제점

```cpp
// 변경 전
void Controller::boostCleaningPower() {
    cleaningUnit_->boostPower();        // BOOSTED
    cleaningUnit_->restoreNormalPower(); // 곧바로 NORMAL
}
```

- 한 폴링 사이클 안에서 부스트가 즉시 취소되어, 파워가 BOOSTED로 **유지되는 구간이 사실상 0**이었다.
- 요구사항 `FR-CLN-02`(먼지 감지 시 **일정 시간 동안** 파워 증가), `FR-CLN-03`(**시간 경과 후** 복귀),
  `UC-07`("설정된 시간이 경과하면 자동 복귀")의 "지속 시간" 개념이 구현되지 않은 상태였다.

## 3. 설계 결정

- "5초"는 실제 경과 시간(wall-clock)이므로 `std::chrono::steady_clock` 기반으로 모델링한다.
- 시뮬레이터는 틱(폴링) 구동 방식(`NFR-PER-03`: 폴링 ≤ 100ms)이므로, 부스트 만료 판정은
  **매 폴링마다** 경과 시간을 확인하는 방식으로 처리한다.
- 단위/시스템 테스트에서 5초를 실제로 기다리지 않고 결정론적으로 검증할 수 있도록,
  Controller에 **시간 소스(clock)를 주입**할 수 있게 한다(기본값은 `steady_clock::now`).

## 4. 변경 내역 (파일별)

### 4.1 `src/rvc/Controller.hpp`
- `#include <chrono>`, `#include <functional>` 추가.
- `using Clock = std::chrono::steady_clock;` 및 부스트 유지 시간 상수
  **`static constexpr std::chrono::milliseconds kBoostDuration{5000};`** 추가.
- 테스트용 시간 주입 메서드 **`void setClock(std::function<Clock::time_point()>)`** 추가.
- 부스트 만료 처리 헬퍼 **`void updateCleaningBoost();`** 선언 추가.
- 멤버 추가: `bool boostActive_`(부스트 진행 여부), `Clock::time_point boostStartedAt_`(시작 시각),
  `std::function<Clock::time_point()> now_`(시간 소스, 기본 `steady_clock`).

### 4.2 `src/rvc/Controller.cpp`
- **`boostCleaningPower()`**: 이미 부스트 중이면 무시(중복 시작 방지), 아니면 `boostPower()` 호출 +
  `boostActive_ = true` + 시작 시각 기록. 즉시 복귀 호출 **제거**.
- **`updateCleaningBoost()` 신규**: 부스트 중이고 `now_() - boostStartedAt_ >= kBoostDuration`이면
  `restoreNormalPower()` 호출 + `boostActive_ = false`.
- **`pollSensors()`**: 최상단(전원 OFF 체크 직후)에서 `updateCleaningBoost()` 호출 →
  장애물 회피로 조기 반환하더라도 부스트 타이머가 계속 진행되어 5초 후 정확히 복귀.
- `startCleaning()` / `powerOff()`: `boostActive_`를 초기화.

### 4.3 `src/simulator/RVCSimulator.hpp`
- 시스템 테스트에서 가상 시간으로 부스트 수명을 검증할 수 있도록
  **`void setClock(...)`** 패스스루 추가(`controller_.setClock(...)`).

## 5. 동작 요약

| 시점 | 동작 |
|---|---|
| 먼지 감지(부스트 미진행) | `boostPower()` 호출, BOOSTED 진입, 시작 시각 기록 |
| 부스트 진행 중 + 5초 이내 | 유지. 먼지가 계속 감지돼도 재부스트하지 않음 |
| 부스트 시작 후 5초 경과 | 다음 폴링에서 `restoreNormalPower()` 호출, NORMAL 복귀 |
| 5초 경과 + 먼지 잔존 | 같은 폴링에서 복귀 직후 재부스트(새 5초 창 시작) |
| 전원 OFF / 청소 시작 | 부스트 상태 초기화 |

## 6. 테스트 수정

### 단위 — `tests/unit/ControllerTest.cpp`
- `UC07_TC003_AfterBoostDuration_PowerIsRestored`: 가상 시간 주입 → 1st poll 부스트 시작,
  5초 경과 후 poll에서 복귀 검증(즉시 복귀가 아님).
- `UC07_TC005_WithinBoostDuration_StaysBoostedNoReboost` **신규**: 5초 이내에는
  `boostPower` 1회만 호출, `restoreNormalPower` 미호출 검증.

### 통합 — `tests/integration/RVCSystemTest.cpp`
- `Scenario4_DustDetected_BoostAndRestore`: 가상 시간으로 부스트 시작 → 5초 후 복귀 시퀀스 검증.
- `Scenario6_NormalCleaningWithDustBoost_CombinedFlow`: 같은 poll에서는 복귀하지 않으므로
  `restoreNormalPower` 기대를 `Times(0)`으로 수정.

### 시스템 — `tests/system/RVCSimulatorTest.cpp`
- `Scenario4_DustyZoneTraversal`: 가상 시간 주입으로 **부스트 라이프사이클 전체**(시작 → 5초 유지·재부스트 없음
  → 만료 후 복귀, 먼지 잔존 시 재부스트) 검증으로 재작성.
- `Scenario5_ObstacleThenDustyZone`: 부스트 직후 파워 단언을 `NORMAL` → **`BOOSTED`** 로 수정.
- `Scenario7_FullRoomCleaningSession` Phase 4: 매 틱 부스트(3회) 기대를 "첫 틱 1회 시작 + 5초 내 유지"로 수정.

## 7. 검증 결과

- 빌드: `cmake --build`(MinGW g++ 15.2, C++17, `-Wall -Wextra -Wpedantic -Werror`) 성공, 경고 0.
- 테스트: `ctest` 기준 **57/57 전체 통과** (unit 43 / integration 6 / system 8).

## 8. 비고

- 부스트 유지 시간(5초)은 `Controller::kBoostDuration` 상수로 한 곳에서 관리한다.
- 실 동작(`rvc_sim`)은 기본 `steady_clock`을 사용하므로, 사용자가 `tick`을 입력하는 간격과 무관하게
  부스트는 시작 후 **실제 5초**가 지나야 복귀한다.
